home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 090 / makehelp.arc / MAKEHELP.DOC < prev    next >
Text File  |  1987-02-05  |  20KB  |  374 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.     ----------------------------------------------------------------------------
  8.        MAKEHELP - System for creating context sensitive help screens in basic 
  9.     ----------------------------------------------------------------------------
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.                   
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.                          MAKEHELP System Operations Manual
  31.                                Revision 1.6  01-30-87
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.                                      Written by
  49.                           Software Consulting Services Inc.
  50.                                   920 Peacock Ave
  51.                                  Palm Bay, Fl 32907
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.     ----------------------------------------------------------------------------
  59.              Copyright (c) 1987,  Software Consulting Services Inc.
  60.   All rights to MAKEHELP (tm) are reserved by Software Consulting Services Inc.
  61.     ----------------------------------------------------------------------------
  62.  
  63.                                                                      Page 1
  64.     MAKEHELP - Written by Software Consulting Services Inc......Rev 1.6 01-30-87
  65.  
  66.     INTRODUCTION TO MAKEHELP SYSTEM
  67.     --------------------------------------
  68.  
  69.     Have you  ever wished that  you could write a  basic program and  have those
  70.     context sensitive  help screens  that you  see in some  of the  high powered
  71.     software like Lotus 1-2-3. Additionally many  times I have created a program
  72.     and after I have completed the project I  find that I still have to create a
  73.     manual to document the operations procedures  of the program. Many a times I
  74.     have  developed a  program for  a client,  spent the  long hours  creating a
  75.     manual of operations  for the new program and delivered  both to the client.
  76.     Several months  later the  client will  call asking  a question  which could
  77.     easily be answered by  the "manual". I find that the  manual is usually left
  78.     on a shelf and never used again.
  79.  
  80.     I believe  that the reason for  this is partially because  the programmer is
  81.     usually not very  good at producing documentation that can  be useful to the
  82.     operator  since the  programmer  will sometimes  "assume"  many things.  The
  83.     manual is  not used since it  is not easy  to find the answers  to questions
  84.     when the operator  does not know how  to phrase the question.  I now provide
  85.     some type of help within the program.   This enables the operator to press a
  86.     <function key> and find out what he/she  needs to know to continue. That way
  87.     the operator does not need to look up  in an index the area in question only
  88.     to  find that  the answer  does not  help in  that particular  operation. Or
  89.     he/she has to look in several places  in the manual to see which explanation
  90.     actually refers to the particular area  in the program. It is something like
  91.     having to know how to spell a word  before one can look up the spelling in a
  92.     dictionary.
  93.  
  94.     The  MAKEHELP system  is a  system  that will  aid the  basic programmer  in
  95.     creating context  sensitive help  screens that  can be  called by  the basic
  96.     program.  These help screens are of a fixed size and shape and are popped up
  97.     on the screen. As expected, the text  on the screen is temporarily saved and
  98.     later redisplayed  so the  program can  continue as  usual. A  subroutine is
  99.     provided that reads the help screens  onto the proper screen memory when the
  100.     <F1>  key is  depressed. The  help screen  will display  until <Any  key> is
  101.     pressed and  then the  program will  resume. The  programmer is  required to
  102.     change a  flag in the  program which will  indicate to the  subroutine which
  103.     help screen is to be popped up. The name of this flag is HFLAG.
  104.  
  105.     For instance as the  program progresses the HFLAG can be  set to: HFLAG=1 so
  106.     that any  time between  now and  the next  change of  HFLAG if  the operator
  107.     presses <F1>,  HELP.001 screen  will pop  up. As  the program  continues the
  108.     programmer will change HFLAG to the appropriate number screen. Any time that
  109.     there is no  help available the subroutine will call  up HELP.000 which will
  110.     popup the message "NO HELP AVAILABLE  HERE!". This is particularly useful in
  111.     the following respect. While the program is being written the programmer can
  112.     keep changing the HFLAG in different areas  of the program. If a help screen
  113.     is  not  written which  matches  the  HFLAG then  the  program  will pop  up
  114.     HELP.000. This  way the programmer can  create the screens later,  but still
  115.     have the  HFLAG designations  within the program  ready for  future writing.
  116.     Additionally  the programmer  can change  ambiguous or  poorly written  help
  117.     screens later, without changing the program  itself. Only the Help screen is
  118.     changed.
  119.  
  120.                                                                      Page 2
  121.     MAKEHELP - Written by Software Consulting Services Inc......Rev 1.6 01-30-87
  122.     
  123.     MAKEHELP.SUB
  124.     ---------------------------- 
  125.  
  126.     The subroutine file, MAKEHELP.SUB, is an ASCII file which can be merged into
  127.     your program  after the fact.  Up in  the front of  the program a  few setup
  128.     procedures are necessary:
  129.  
  130.     1) Place the instructions       KEY (1),"":KEY (1) ON:ON KEY (1) GOSUB 25000
  131.        ** These will cause the program to branch to the help subroutine whenever
  132.        the operator pressed the <F1> function key.
  133.  
  134.     2) Place  the  instruction    MONITOR$="C"  if  the system that will run the
  135.        program is a CGA display adaptor.
  136.  
  137.     3) Alternately the instruction  MONITOR$="M" if the system that will run the
  138.        program is an IBM monochrome monitor display adaptor.
  139.  
  140.     4) Throughout the program whenever  there is a pause or stop for input place
  141.        the instruction HFLAG=X where X is the number of the help screen that you
  142.        want  displayed at that point.  Be sure to set the HFLAG before the pause
  143.        or stop for input. That way the operator will see the proper help screen.
  144.  
  145.     5) It is a good idea to place an HFLAG=X at every stop/pause even if no help
  146.        has been created yet for that spot. The program will automatically pop up
  147.        HELP.000 in the event that it does not  find a corresponding help screen.
  148.        That means  that later  when the  content  of the  missing help screen is
  149.        better defined that help screen can be added after-the-fact.
  150.  
  151.     6) HINT:  The  HFLAG  can revert back to a previous condition if the program
  152.        requires. For instance, if a help screen was provided which described the
  153.        use of the program's  menu system, the  same help screen can be called at
  154.        every menu. This would be done by setting  the HFLAG variable to the same
  155.        number just before every display of a menu.
  156.     7) HINT:  The best control  of operator input  is a subroutine  created that
  157.        uses the basic inkey$ instruction. This MAKEHELP.SUB requires that a loop
  158.        is taking place when the <F1> key is pressed. For example, if the program
  159.        is written using the basic INPUT  instuction the scanning of the keyboard
  160.        is devoted to that instruction.  Therefore honoring the depression of the
  161.        <F1>  key will  not  take place  until after  the  INPUT instruction  has
  162.        completed. This would  be inconvenient for a practical  help system since
  163.        the help screen  should be displayed when the operator  requires the help
  164.        which is usually during input of data. The solution to to this problem is
  165.        to provide for data input in the form of an inkey$ routine which would be
  166.        a loop of  instructions scanning the keyboard for  input characters. This
  167.        would allow the ON  KEY (1) GOSUB 25000 instruction to  react to the <F1>
  168.        key as required. An example of an inkey$ input routine is as follows:
  169.        
  170.     29999 'SET ZLIM TO MAX # LENGTH OF STRING, GOSUB 30000, SUBROUTINE RETURNS 
  171.            STRING IN Z$
  172.     30000 ZZ$="":TL%=CSRLIN:TC%=POS(0):IF ZLIM=0 THEN ZLIM=30
  173.     30010 LOCATE TL%,TC%:PRINT"["+STRING$(ZLIM," ")+"]";
  174.     30020 Z$=INKEY$:IF Z$="" THEN 30020
  175.     30030 IF Z$=CHR$(13) THEN Z$=ZZ$:RETURN ELSE IF Z$=CHR$(8) AND LEN(ZZ$)>0
  176.           THEN ZZ$=LEFT$(ZZ$,LEN(ZZ$)-1):Z$=" ":GOTO 30060 ELSE IF Z$=CHR$(8)    
  177.           AND LEN(ZZ$)=0 THEN BEEP:GOTO 30020
  178.     30040 Z%=INSTR(" 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ",Z$):             
  179.           IF Z%=0 THEN BEEP:GOTO 30020
  180.     30050 IF LEN(ZZ$)<ZLIM THEN ZZ$=ZZ$+Z$:LOCATE TL%,TC%+LEN(ZZ$):PRINT Z$;:    
  181.           GOTO 30020 ELSE BEEP:GOTO 30020
  182.     30060 LOCATE TL%,TC%+LEN(ZZ$)+1:PRINT Z$;:GOTO 30020
  183.       
  184.                                                                      Page 3
  185.     MAKEHELP - Written by Software Consulting Services Inc......Rev 1.6 01-30-87
  186.  
  187.  
  188.     MAKEHELP.EXE
  189.     ------------------------------------
  190.  
  191.  
  192.     MAKEHELP.EXE  is a  mini  wordprocessor which  facilitates  creating a  help
  193.     screen for use in the above examples.  It is the "heart" of the help system.
  194.     MAKEHELP.EXE  creates  a window  into  which  the  programmer can  type  the
  195.     appropriate help message.  The resulting screen can be given  a number so it
  196.     can be called later  by a program. If the programmer  has a particular style
  197.     that is  reflected in his/her  operator input  routines etc. then  a generic
  198.     help screen can be created for a particular favorite subroutine. Then in the
  199.     future  whenever  that  subroutine  is  used in  a  subsequent  program  the
  200.     appropriate help screen  can be included. In  that case the HFLAG  is set in
  201.     the subroutine so it's use will  always dictate a particular help screen. An
  202.     example might be  an operator request for Yes/No might  come from a favorite
  203.     subroutine  that  the programmer  always  uses  for  that purpose.  All  the
  204.     programmer must  do is create  the help  describing how the  operator should
  205.     answer Yes/No with one key stroke of "y"  or "n" in upper or lower case etc.
  206.     The HFLAG would  be set in the  Yes/No subroutine and any  time the operator
  207.     pressed <F1>  when in that subroutine  the generic Yes/No help  screen would
  208.     pop up. Now since  the generic Yes/No help screen was  already created a few
  209.     projects ago, the programmer need only copy the appropriate HELP.XXX file to
  210.     the disk.
  211.  
  212.  
  213.  
  214.     MAKEHELP.EXE  is a  primitive word  processor  and only  supplies a  limited
  215.     amount  of necessary  features.  However  it is  versatile  enough  to be  a
  216.     valuable tool  in the  creation of  context sensitive  help screens.  When I
  217.     first set out to  solve this problem I thought about merging  in a text file
  218.     from  another source  like EDLIN,  or WORDSTAR  or any  other favorite  word
  219.     processor. I weighed out the advantages and the disadvantages and settled on
  220.     a  self-contained system  which  did not  require the  ownership  of a  word
  221.     processor  or the  knowledge  of it's  use. Anyone  who  would require  this
  222.     program's capability already  knows enough about their computer  to use this
  223.     program. That  is, the use of  the <Insert>, <Delete>, <Up>,  <Down>, <Left>
  224.     <Right>, <Home>, <End>, <Backspace>, <Tab>, and <Enter> keys. These all work
  225.     as one might expect them to while  editing a window of text. Wordwrap is not
  226.     provided at this time (but I might add this feature in the future). Only one
  227.     feature is provided for that is not  inherent in the use of the cursor keys.
  228.     This feature is  the CENTERING feature, which will  automatically center the
  229.     current line  within the  help screen  window for titles,  etc. It's  use is
  230.     described below.  MAKEHELP.EXE provides a  window into which  the programmer
  231.     can type the  appropriate text. This window does not  have the usual cursor.
  232.     The position of the invisible cursor is  indicated by a group of arrows that
  233.     follow this  position outside the window.  That is, above and  below the box
  234.     two arrows follow the cursor left and  right. And, on the left and right two
  235.     arrows  follow  the current  line  up  and  down.  The intersection  of  the
  236.     imaginary "crosshair"  between these arrows  is the current position  of the
  237.     invisable cursor.  The current line  is indicated by  the two arrows  at the
  238.     extreme left and right. The current column is indicated by the two arrows at
  239.     the top and bottom of the help window. It is much easier to get used to than
  240.     it is to explain in this document.
  241.  
  242.                                                                      Page 4
  243.     MAKEHELP - Written by Software Consulting Services Inc......Rev 1.6 01-30-87
  244.                                            
  245.     MAKEHELP.EXE FUNCTION KEY ASSIGNMENTS
  246.     --------------------------------------------
  247.  
  248.     MAKEHELP.EXE  makes use  of  the  <Function keys>  to  provide the  commands
  249.     required  to CLEAR,  TEST,  EDIT, SAVE,  EXIT the  program,  and CENTER  the
  250.     current line. These functions are explained as follows:
  251.  
  252.     <ESC> = CLEAR box
  253.     If this function is  invoked the program will ask if "you  are sure that you
  254.     want to clear  the box  Y/N". You  can answer this question  by pressing the
  255.     "Y"  or the  "N" key  or you  can indicate  YES by  pressing the  <Enter> or
  256.     <Return> key. If you  answer "N" you will be returned to  where you left off
  257.     to  continue editing  the help  screen.  If you  answer "Y"  or <Enter>  the
  258.     program will  clear out the  window and  place underlines to  indicate blank
  259.     characters.  On  the  color  graphics  system the  underlines  will  all  be
  260.     connected.  However, on  the monochrome  adapter each  character is  obvious
  261.     since each  underline has a  tiny space between  it and the  next underline.
  262.     There are advantages and disadvantages to each type of adapter.
  263.  
  264.     <F1> = TEST a help screen
  265.     This function will allow the programmer to display a previously created help
  266.     screen  as the  operator  would see  it  in the  final  program. No  special
  267.     instuctions are required since the program will ask for the name of the help
  268.     screen requested  for display. The  number need  not be padded  with leading
  269.     zeros since the program will automatically provide them. For example, if the
  270.     help  screen number  typed  and <Enter>'d  was 34,  then  the program  would
  271.     display the help screen  HELP.034. After  display any key will return you to
  272.     a blank help window so you may edit a new screen.
  273.  
  274.     <F2> = EDIT a help screen
  275.     This function  is provided so  that you can  edit a previously  created help
  276.     screen. Assume  that you  have created  a help screen  some time  ago, whose
  277.     layout or  form you desire  to duplicate. Or, assume  that you have  what is
  278.     considered  a  generic  help  screen  that  you  want  to  customize  to  an
  279.     application. This function will facilitate  the above requirements. You will
  280.     be asked for  a help screen number.  The entry of the help  screen number is
  281.     the same as  explained above. When the  help screen is loaded it  will be as
  282.     though you just  typed it in at  this session. You will have  the ability to
  283.     edit the screen as you see fit.  When you have completed your editing of the
  284.     help screen in question,  you will need to save it under the  same name or a
  285.     different name. This brings us to the next section on SAVE a help screen.
  286.  
  287.     <F4> = SAVE help screen
  288.     This function will  save the currently displayed help screen  to a file with
  289.     the name  HELP.XXX where XXX is  the number that  you want to give  the help
  290.     screen. If  you have  called in a  help screen with  <F2> then  the original
  291.     number  will be  displayed as  a  default number.  If  you do  not want  the
  292.     original number for this SAVE then type  a new number. If the number already
  293.     exists on  the disk then you  will be asked  if you desire to  overwrite the
  294.     existing file with the new one.
  295.  
  296.     <F9> = EXIT program
  297.     To EXIT the MAKEHELP program you press <F9>. Confirmation of this request is
  298.     required, afterwhich you will be returned to DOS.
  299.  
  300.     <F10> = CENTER current line
  301.     Whenever it is required to center a line you can position your cursor arrows
  302.     on the line to center and press <F10>. For example one might go to the first
  303.     line of a help  screen and type a title at the left  margin of the box. Then
  304.     when <F10> is pressed the title that was at the left margin will be centered
  305.     on the line.
  306.  
  307.                                                                      Page 5
  308.     MAKEHELP - Written by Software Consulting Services Inc......Rev 1.6 01-30-87
  309.  
  310.     LIMITED LICENSE
  311.     --------------------------------
  312.  
  313.     The MAKEHELP system is copyrighted but a LIMITED LICENSE is granted. You are
  314.     free to use ans share it under the following conditions:
  315.  
  316.     1) MAKEHELP is not distributed in modified form.
  317.     2) MAKEHELP is distributed with this documentation file.
  318.     3) No fee or other consideration is charged for copying the files that make
  319.        up the MAKEHELP system.
  320.     4) Reference to the copyright and author is retained.
  321.  
  322.     WARRANTY
  323.     --------------------------------
  324.  
  325.     The MAKEHELP system is provided "as is" without warranty of any kind, either
  326.     expressed or implied,  including, but not limited to  the implied warranties
  327.     of merchantability and fitness for a particular purpose. The author's entire
  328.     liability will be  limited to the total amount of  money the individual user
  329.     paid  directly and  explicitly to  the author  for the  use of  the MAKEHELP
  330.     system.
  331.  
  332.     REGISTRATION
  333.     --------------------------------
  334.  
  335.     The MAKEHELP system is  provided free of charge to anyone  who wishes to use
  336.     it under  the LIMITED LICENSE as  described above. However, if  you register
  337.     your copy of MAKEHELP with  Software Consulting Services we will send you  a
  338.     serialized copy of  the latest version of the MAKEHELP  system. You can make
  339.     copies and  distribute them  to as  many basic programmers  as you  wish who
  340.     might have use for the MAKEHELP system. Whenever someone registers a copy of
  341.     your serial number with  us, We will send you a check  for $10.00. Make sure
  342.     that  whenever you  copy  the MAKEHELP  system that  you  encourage the  new
  343.     programmer/user to  register their  copy of the  MAKEHELP system.  This will
  344.     insure that  you get $10.00  for every copy of  the MAKEHELP system  that is
  345.     registered with your serial number.
  346.  
  347.     In order to register this copy of the MAKEHELP system with us follow these
  348.     instuctions:
  349.  
  350.     1) Send a $20.00 contribution to:   SCS Inc.
  351.                                         920 Peacock Ave NE
  352.                                         Palm Bay, FL   32907
  353.     2)  Include the  Serial number and  the revision  number  which is 
  354.         shown in  the  upper right-hand  corner  of  the  MAKEHELP.EXE
  355.         screen, along with  your NAME  and ADDRESS.  Please  print the 
  356.         above as if your money depended on it. IT DOES !
  357.     3)  You will be sent copy of  the MAKEHELP system with your serial
  358.         number  in it.  We will  send this  copy by  return mail  on a
  359.         Double Density,  Double    Sided  diskette. You can  then copy
  360.         from that disk as many copies of the    MAKEHELP system as you
  361.         wish. REMEMBER,  you will receive $10.00  for every subsequent
  362.         registration received with your serial number on it.
  363.         
  364.     Thanx and enjoy,
  365.  
  366.     Denny Mela
  367.     Software Consulting Services, Inc.
  368.  
  369. F
  370. #(-27<Fé               
  371.     Thanx and enjoy,
  372.  
  373.     Denny Mela
  374.